使用Android Studio把自己的Android library分发到JCenter

发表于 | 分类于 | |

前言

如果你想在Android Studio中引入一个library到你的项目，你只需添加如下的一行代码到模块的build.gradle文件中:

1
compile 'com.sherlockshi.widget:aspectratioimageview:1.0.1'

就是如此简单的一行代码，你就可以使用这个library了。

酷呆了。不过你可能很好奇Android Studio是从哪里得到这个library的。这篇文章将详细讲解这是怎么回事，包括如何把你的库发布出去分享给世界各地的其他开发者，这样不仅可以让世界更美好，还可以耍一次酷。

一、Android studio 是从哪里得到库的？

先从这个简单的问题开始，我相信不是每个人都完全明白Android studio 是从哪里得到这些library的。莫非就是Android studio 从google搜索然后下载了一个合适的给我们？

呵呵，没那么复杂。Android Studio是从build.gradle里面定义的Maven 仓库服务器上下载library的。Apache Maven是Apache开发的一个工具，提供了用于贡献library的文件服务器。总的来说，只有两个标准的Android library文件服务器：JCenter 和 Maven Central。

1. JCenter

JCenter是一个由bintray.com维护的Maven仓库 。你可以在这里看到整个仓库的内容。
我们在项目的build.gradle 文件中如下定义仓库，就能使用JCenter了：

1
2
3
4
5
allprojects {
    repositories {
        jcenter()
    }
}

2. Maven Central

Maven Central 则是由sonatype.org维护的Maven仓库。你可以在这里看到整个仓库。

注：不管是JCenter还是Maven Central ，两者都是Maven仓库

我们在项目的build.gradle 文件中如下定义仓库，就能使用Maven Central了：

1
2
3
4
5
allprojects {
    repositories {
        mavenCentral()
    }
}

注意，虽然JCenter和Maven Central 都是标准的 android library仓库，但是它们维护在完全不同的服务器上，由不同的人提供内容，两者之间毫无关系。在JCenter上有的可能 Maven Central 上没有，反之亦然。

除了两个标准的服务器之外，如果我们使用的library的作者是把该library放在自己的服务器上，我们还可以自己定义特有的Maven仓库服务器。Twitter的Fabric.io 就是这种情况，它们在 https://maven.fabric.io/public 上维护了一个自己的Maven仓库。如果你想使用Fabric.io的library，你必须自己如下定义仓库的url。

1
2
3
repositories {
    maven { url 'https://maven.fabric.io/public' }
}

然后在里面使用相同的方法获取一个library:

1
compile 'com.crashlytics.sdk.android:crashlytics:2.2.4@aar'

但是将library上传到标准的服务器与自建服务器，哪种方法更好呢？当然是前者。如果将我们的library公开，其他开发者除了一行定义依赖名的代码之外不需要定义任何东西。因此这篇文章中，我们将只关注对开发者更友好的JCenter 和 Maven Central 。

实际上可以在Android Studio上使用的除了Maven 仓库之外还有另外一种仓库：Ivy 仓库 。但是根据我的经验来看，我还没看到任何人用过它，包括我，因此本文就直接忽略了。

二、理解JCenter和Maven Central

为何有两个标准的仓库？

事实上两个仓库都具有相同的使命：提供Java或者Android library服务。上传到哪个（或者都上传）取决于开发者。

起初，Android Studio 选择Maven Central作为默认仓库。如果你使用老版本的Android Studio创建一个新项目，mavenCentral()会自动的定义在build.gradle中。

但是Maven Central的最大问题是对开发者不够友好。上传library异常困难。上传上去的开发者都是某种程度的极客。同时还因为诸如安全方面的其他原因，Android Studio团队决定把默认的仓库替换成JCenter。正如你看到的，一旦使用最新版本的Android Studio创建一个项目，JCenter()自动被定义，而不是mavenCentral()。

有许多将Maven Central替换成JCenter的理由，下面是几个主要的原因。

  • JCenter通过CDN发送library，开发者可以享受到更快的下载体验。
  • JCenter是全世界最大的Java仓库，因此在Maven Central 上有的，在JCenter上也极有可能有。换句话说JCenter是Maven Central的超集。
  • 上传library到仓库很简单，不需要像在Maven Central上做很多复杂的事情。
  • 友好的用户界面
  • 如果你想把library上传到Maven Central ，你可以在bintray网站上直接点击一个按钮就能实现。

基于上面的原因以及我自己的经验，可以说替换到JCenter是明智之举。

所以我们这篇文章将把重心放在JCenter，反正如果你能成功把library放在JCenter，转到 Maven Central 是非常容易的事情。

三、gradle是如何从仓库上获取一个library的？

在讨论如何上传library到JCenter之前，我们先看看gradle是如何从仓库获取library的。比如我们在 build.gradle输入如下代码的时候，这些库是如果奇迹般下载到我们的项目中的。

1
compile 'com.sherlockshi.widget:aspectratioimageview:1.0.1'

一般来说，我们需要知道library的字符串形式，包含3部分

1
GROUP_ID:ARTIFACT_ID:VERSION

上面的例子中，GROUP_ID是com.sherlockshi.widget，ARTIFACT_ID是aspectratioimageview，VERSION是1.0.1。

GROUP_ID定义了library的group。有可能在同样的上下文中存在多个不同功能的library。如果library具有相同的group，那么它们将共享一个GROUP_ID。通常我们以开发者包名紧跟着library的group名称来命名，比如com.squareup.picasso。然后ARTIFACT_ID中是library的真实名称。至于VERSION，就是版本号而已，虽然可以是任意文字，但是我建议设置为x.y.z的形式，如果喜欢还可以加上beta这样的后缀。

下面是Square library的一个例子。你可以看到每个都可以很容易的分辨出library和开发者的名称。

1
2
3
4
5
6
dependencies {
  compile 'com.squareup:otto:1.3.7'
  compile 'com.squareup.picasso:picasso:2.5.2'
  compile 'com.squareup.okhttp:okhttp:2.4.0'
  compile 'com.squareup.retrofit:retrofit:1.9.0'
}

那么在添加了上面的依赖之后会发生什么呢？简单。Gradle会询问Maven仓库服务器这个library是否存在，如果是，gradle会获得请求library的路径，一般这个路径都是这样的形式：GROUP_ID/ARTIFACT_ID/VERSION_ID。比如可以在http://jcenter.bintray.com/com/squareup/otto/1.3.7 和 https://oss.sonatype.org/content/repositories/releases/com/squareup/otto/1.3.7/
下获得com.squareup:otto:1.3.7的library文件。

然后Android Studio 将下载这些文件到我们的电脑上，与我们的项目一起编译。整个过程就是这么简单，一点都不复杂。

我相信你应该清楚的知道从仓库上下载的library只是存储在仓库服务器上的jar 或者aar文件而已。有点类似于自己去下载这些文件，拷贝然后和项目一起编译。但是使用gradle依赖管理的最大好处是你除了添加几行文字之外啥也不做。library一下子就可以在项目中使用了。

四、了解aar文件

等等，我刚才说了仓库中存储的有两种类型的library：jar 和 aar。jar文件大家都知道，但是什么是aar文件呢？

aar文件时在jar文件之上开发的。之所以有它是因为有些Android Library需要植入一些安卓特有的文件，比如AndroidManifest.xml，资源文件，Assets或者JNI。这些都不是jar文件的标准。

因此aar文件就时发明出来包含所有这些东西的。总的来说它和jar一样只是普通的zip文件，不过具有不同的文件结构。jar文件以classes.jar的名字被嵌入到aar文件中。其余的文件罗列如下：
– /AndroidManifest.xml (mandatory)
– /classes.jar (mandatory)
– /res/ (mandatory)
– /R.txt (mandatory)
– /assets/ (optional)
– /libs/.jar (optional)
– /jni//.so (optional)
– /proguard.txt (optional)
– /lint.jar (optional)
可以看到.aar文件是专门为安卓设计的。因此这篇文章将教你如何创建与上传一个aar形式的library。

五、如何上传library到JCenter

我相信你已经知道了仓库系统的大体工作原理。现在我们来开始最重要的部分：上传。这个任务和如何上传library文件到http://jcenter.bintray.com 一样简单。如果做到，这个library就算发布了。好吧，有两个需要考虑：如何创建aar文件以及如何上传构建的文件到仓库。

虽然需要若干步骤，但是我还是想强调这事并不复杂，因为已经准备好了所有事情。整个过程如下图：

因为细节比较多，我分为以下几个部分，一步一步的详细解释清楚。

1. 在bintray上创建package

第一步

在bintray.com上注册一个账号。（注册过程很简单，自己完成，也可以直接使用Github账号）

第二步

完成注册之后，登录网站，然后点击+号

第三步

输入Repository相关信息，创建一个Repository

第四步

点击打开刚才创建好的Repository

第五步

点击Add New Package，为我们的library创建一个新的package

第六步

按页面要求填写相关信息

完工！现在你有了自己在Bintray上的Maven仓库，可以准备上传library到上面了。

2. 准备一个Android Studio项目

很多情况下，我们需要同时上传一个以上的library到仓库，也可能不需要上传东西。因此我建议最好将每部分分成一个Module。最好分成两个module，一个Application Module一个Library Module。Application Module用于展示库的用法，Library Module是library的源代码。如果你的项目有一个以上的library，尽量创建另外的module：1个 module对应1 个library。

我相信大家知道如何创建一个新的module，因此就不会深入讲解这个问题了。其实很简单，基本就是选择 File -> New -> Module，选择Android Library，然后就完了。

添加bintray插件

我们需要修改项目的build.gradle文件中的依赖部分，如下：

1
2
3
4
5
dependencies {
    ...
    classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.6'
    classpath 'com.github.dcendents:android-maven-gradle-plugin:1.4.1'
}

配置Bintray账号以及开发者信息

接下来我们将修改local.properties。在里面定义api key的用户名以及被创建key的密码，用于bintray的认证。之所以要把这些东西放在这个文件是因为这些信息时比较敏感的，不应该到处分享，包括版本控制里面。幸运的是在创建项目的时候local.properties文件就已经被添加到.gitignore了。因此这些敏感数据不会被误传到git服务器。

下面是要添加的代码：

1
2
3
4
5
6
7
8
#bintray
bintray.user=******
bintray.apikey=******

#developer
developer.id=******
developer.name=******
developer.email=******
  • bintray.user：你的Bintray的用户名
  • bintray.apikey：你的的Bintray的API Key,可以在Edit Profile页面的 API Key 选项卡中找到
  • developer.id：通常是你在开源社区的昵称
  • developer.name：你的姓名
  • developer.email：你的邮箱

配置项目信息

在library module目录下新建project.properties文件，输入以下内容：

1
2
3
4
5
6
7
8
9
10
11
#project
project.name=AspectRatioImageView
project.bintrayRepo=android-widgets
project.groupId=com.sherlockshi.widget
project.artifactId=aspectratioimageview
project.packaging=aar
project.siteUrl=https://github.com/SherlockShi/AspectRatioImageView
project.gitUrl=https://github.com/SherlockShi/AspectRatioImageView.git

#javadoc
javadoc.name=AspectRatioImageView
  • project.name：项目名称
  • project.groupId：项目组ID
  • project.artifactId：项目ID
  • project.packaging：包类型，Android库是aar
  • project.siteUrl：项目官方网站的地址，没有的话就用Github上的地址
  • project.gitUrl：项目的Git地址
  • javadoc.name：生成的javadoc打开后主页显示的名称，通常跟项目名称一样即可

配置bintrayUpload.gradle

本步骤也可以直接使用别人打包好的脚本引入即可，但本文主要介绍原理，有需要的可以自己搜索。

  • 首先在library module目录下新建bintrayUpload.gradle文件，直接粘贴以下内容： 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
apply plugin: 'com.github.dcendents.android-maven'
apply plugin: 'com.jfrog.bintray'

// load properties
Properties properties = new Properties()
File localPropertiesFile = project.file("../local.properties");
if(localPropertiesFile.exists()){
    properties.load(localPropertiesFile.newDataInputStream())
}
File projectPropertiesFile = project.file("project.properties");
if(projectPropertiesFile.exists()){
    properties.load(projectPropertiesFile.newDataInputStream())
}

// read properties
def projectName = properties.getProperty("project.name")
def projectBintrayRepo = properties.getProperty("project.bintrayRepo")
def projectGroupId = properties.getProperty("project.groupId")
def projectArtifactId = properties.getProperty("project.artifactId")
def projectVersionName = android.defaultConfig.versionName
def projectPackaging = properties.getProperty("project.packaging")
def projectSiteUrl = properties.getProperty("project.siteUrl")
def projectGitUrl = properties.getProperty("project.gitUrl")

def developerId = properties.getProperty("developer.id")
def developerName = properties.getProperty("developer.name")
def developerEmail = properties.getProperty("developer.email")

def bintrayUser = properties.getProperty("bintray.user")
def bintrayApikey = properties.getProperty("bintray.apikey")

def javadocName = properties.getProperty("javadoc.name")

group = projectGroupId

// This generates POM.xml with proper parameters
install {
    repositories.mavenInstaller {
        pom {
            project {
                name projectName
                groupId projectGroupId
                artifactId projectArtifactId
                version projectVersionName
                packaging projectPackaging
                url projectSiteUrl
                licenses {
                    license {
                        name 'The Apache Software License, Version 2.0'
                        url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
                    }
                }
                developers {
                    developer {
                        id developerId
                        name developerName
                        email developerEmail
                    }
                }
                scm {
                    connection projectGitUrl
                    developerConnection projectGitUrl
                    url projectSiteUrl
                }
            }
        }.writeTo("$buildDir/poms/pom-default.xml").writeTo("pom.xml")
    }
}

// This generates sources.jar
task sourcesJar(type: Jar) {
    from android.sourceSets.main.java.srcDirs
    classifier = 'sources'
}

task javadoc(type: Javadoc) {
    source = android.sourceSets.main.java.srcDirs
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
}

// This generates javadoc.jar
task javadocJar(type: Jar, dependsOn: javadoc) {
    classifier = 'javadoc'
    from javadoc.destinationDir
}

artifacts {
    archives javadocJar
    archives sourcesJar
}

// javadoc configuration
javadoc {
    options{
        encoding "UTF-8"
        charSet 'UTF-8'
        author true
        version projectVersionName
        links "http://docs.oracle.com/javase/7/docs/api"
        title javadocName
    }
}

// bintray configuration
bintray {
    user = bintrayUser
    key = bintrayApikey
    configurations = ['archives']
    pkg {
        repo = projectBintrayRepo
        name = projectName
        websiteUrl = projectSiteUrl
        vcsUrl = projectGitUrl
        licenses = ["Apache-2.0"]
        publish = true
    }
}
  • 然后修改你的library module的build.gradle文件，在最后加上：
1
apply from: "bintrayUpload.gradle"

3. 把library上传到你的bintray空间

打开终端进入项目目录下，执行gradlew bintrayUpload命令即可

另外，如果你的本地已经配置了Gradle了，那么执行gradle bintrayUpload命令也可以。gradlew是Gradle的一层封装，如果你本地没有安装Gradle, gradlew就会自动下载Gradle。

在bintray的网页上检查一下你的package。你会发现在版本区域的变化。

点击进去，进入Files选项卡，你会看见那里有我们所上传的library文件。

恭喜，你的library终于放在了互联网上，任何人都可以使用了！

不过也别高兴过头，library现在仍然只是在你自己的Maven仓库，而不是在JCenter上。如果有人想使用你的library，他必须定义仓库的url，如下：

1
2
3
4
5
6
7
8
9
10
11
repositories {
    maven {
        url 'https://dl.bintray.com/sherlockshi/android-widgets/'
    }
}

...

dependencies {
    compile 'com.sherlockshi.widgets:aspectratioimageview:1.0.1'
}

你可以在bintray的web界面找到自己Maven仓库的url，或者直接吧nuuneoi替换成你的bintray用户名（因为前面部分其实都是一样的）。我还建议你直接访问那个链接，看看里面到底是什么。

但是，就如我们前面所讲的那样，让开发者去定义url这种复杂的事情并不是分享library的最佳方式。想象一下，使用10个library不得添加10个url？所以为了更好的体验，我们把library从自己的仓库传到JCenter上。

4. 同步bintray用户仓库到JCenter

把library同步到JCenter非常容易，只需访问网页在package界面Linked To区域点击右下角的Add to JCenter，什么也不用填，直接点击Send。

现在我们所能做的就是等待bintray团队审核我们的请求，大概4-5个小时。一旦同步的请求审核通过，你会收到一封确认此更改的邮件。现在我们去网页上确认，你会在 Linked To 部分看到已链接到JCenter仓库。

5. 用法

从此之后，任何开发者都可以使用JCenter() repository 外加一行gradle脚本来使用我们的library了

1
compile 'com.sherlockshi.widget:aspectratioimageview:1.0.1'

想检查一下自己的library在JCenter上是否存在？你可以直接访问http://jcenter.bintray.com ，然后进入和你library的group id 以及artifact id匹配的目录。在本例中就是com -> sherlockshi -> widget -> aspectratioimageview -> 1.0.1。

请注意链接到JCenter是一个只需做一次的操作。如果你对你的package做了任何修改，比如上传了一个新版本的binary，删除了旧版本的binary等等，这些改变也会影响到JCenter。不过毕竟你自己的仓库和JCenter在不同的地方，所以需要等待2－3分钟让JCenter同步这些修改。

同时注意，如果你决定删除整个package，放在JCenter仓库上的library不会被删除。它们会像僵尸一样的存在，没有人再能删除它了。因此我建议，如果你想删除整个package，请在移除package之前先在网页上删除每一个版本。

恭喜！虽然需要许多步骤，但是每一步都很简单。而且大部分操作都是一劳永逸的。

期待能在上面看到你的library大作！

六、踩坑经历

1. 编译上传时，提示jar包未找到

1
2
:aspectratioimageview:bintrayUpload: file /Users/sherlock/work/workspace/AndroidStudio/AspectRatioImageView/aspectratioimageview/build/libs/aspectratioimageview-1.0.1-javadoc.jar could not be found.
:aspectratioimageview:bintrayUpload: file /Users/sherlock/work/workspace/AndroidStudio/AspectRatioImageView/aspectratioimageview/build/libs/aspectratioimageview-1.0.1-sources.jar could not be found.

解决方法：
先执行gradlew install，再执行gradlew bintrayUpload

2. Javadoc generation failed

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
:sherlockspinner:javadoc
/path/.../xxx.java:7: 错误: 程序包android.support.annotation不存在
import android.support.annotation.ColorInt;
                                 ^
/path/.../xxx.java:8: 错误: 程序包android.support.annotation不存在
import android.support.annotation.ColorRes;
                                 ^
/path/.../xxx.java:9: 错误: 程序包android.support.annotation不存在
import android.support.annotation.DrawableRes;
                                 ^
/path/.../xxx.java:10: 错误: 程序包android.support.v4.content不存在
import android.support.v4.content.ContextCompat;
                                 ^
/path/.../xxx.java:11: 错误: 程序包android.support.v4.view不存在
import android.support.v4.view.ViewCompat;
                              ^
/path/.../xxx.java:12: 错误: 程序包android.support.v7.widget不存在
import android.support.v7.widget.AppCompatEditText;
                                ^
/path/.../xxx.java:13: 错误: 程序包android.support.v7.widget不存在
import android.support.v7.widget.ListPopupWindow;
                                ^
/path/.../xxx.java:27: 错误: 找不到符号
public class SherlockSpinner extends AppCompatEditText {
                                     ^
  符号: 类 AppCompatEditText
/path/.../xxx.java:35: 错误: 找不到符号
    private ListPopupWindow mListPopupWindow;
            ^
  符号:   类 ListPopupWindow
  位置: 类 SherlockSpinner
/path/.../xxx.java:140: 错误: 找不到符号
    public void setLineColorResource(@ColorRes int resId) {
                                      ^
  符号:   类 ColorRes
  位置: 类 SherlockSpinner
/path/.../xxx.java:149: 错误: 找不到符号
    public void setLineColor(@ColorInt int color) {
                              ^
  符号:   类 ColorInt
  位置: 类 SherlockSpinner
/path/.../xxx.java:208: 错误: 找不到符号
    public void setDropdownIcon(@DrawableRes int resId) {
                                 ^
  符号:   类 DrawableRes
  位置: 类 SherlockSpinner
/path/.../xxx.java:138: 警告: @param 没有说明
     * @param resId
       ^
/path/.../xxx.java:147: 警告: @param 没有说明
     * @param color
       ^
/path/.../xxx.java:170: 错误: 找不到引用
     * @see #setClickable(boolean)
            ^
/path/.../xxx.java:172: 警告 - 标记@see: 在com.sherlockshi.widget.SherlockSpinner中找不到setClickable(boolean)
/path/.../xxx.java:206: 警告: @param 没有说明
     * @param resId
       ^
javadoc: 警告 - 找不到类ColorRes。
javadoc: 警告 - 找不到类ColorInt。
javadoc: 警告 - 找不到类DrawableRes。
1 个错误
19 个警告
:sherlockspinner:javadoc FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':sherlockspinner:javadoc'.
> Javadoc generation failed. Generated Javadoc options file (useful for troubleshooting): '/Users/sherlock/work/workspace/AndroidStudio/SherlockSpinner/sherlockspinner/build/tmp/javadoc/javadoc.options'

解决方法：

  • 错误: 编码GBK的不可映射字符 ——注释不要用中文，或者修改项目的字符编码
  • 错误: 找不到符号——删除javadoc里所有的html标签

删除@see #setClickable(boolean)这一行代码注释。

七、参考

如何使用Android Studio把自己的Android library分发到JCenter和Maven Central

5分钟发布Android Library项目到JCenter

使用JitPack发布Android开源库

感谢你的支持，让我继续努力分享有用的技术和知识点!